/*
 * File     : NativeString.java
 * Created  : 22 Apr 2011
 *
 * Copyright © 2011 Matthew Wilson (mj. {my-surname} .uk {at} gmail.com)
 *
 * This program is free software: you can redistribute it and/or modify
 * it under the terms of the GNU Lesser General Public License as published by
 * the Free Software Foundation, either version 3 of the License, or
 * (at your option) any later version.
 *
 * This program is distributed in the hope that it will be useful,
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 * GNU Lesser General Public License for more details.
 *
 * You should have received a copy of the GNU Lesser General Public License
 * along with this program.  If not, see <http://www.gnu.org/licenses/>.
 */
package com.googlecode.dni.type;

import com.googlecode.dni.library.Library;


/**
 * <p>
 *  Encapsulates a string in a form appropriate for a native call.
 * </p>
 * <p>
 *  This type makes no distinction between the various encoding options for
 *  native strings; it is simply a wrapper for an array of native characters.
 * </p>
 * <p>
 *  Most strings are considered immutable; only {@link NativeStringBuffer}s
 *  should be consider mutable.
 * </p>
 *
 * @author Matthew Wilson
 */
public interface NativeString extends FreeableNativeObject
{

    /**
     * <p>
     *  Reads the native string, using the given charset.
     * </p>
     *
     * @param charset
     *            the charset;
     *            or {@link Library#DEFAULT_CHARSET} for the default charset,
     *            or {@link Library#WIDE_CHARSET} for the wide charset;
     *            may be ignored if the string already knows the stored charset
     * @return the string
     */
    String read( String charset );

}
